NAV Navbar
shell ruby python javascript
  • Introduction
  • Authentication
  • Crop Suitability
  • Weather
  • Air Quality
  • Populations
  • Satellites
  • Errors
  • Introduction

    Welcome to the Radiant Earth Foundation Data API! You can use our API to access Radiant Earth Foundation API endpoints, which can get information on various data sets including weather, air quality, population, global health, satellite ephemeris, machine learning APIs, and other partner data.

    The Radiant Earth Foundation Data API is located at https://api.radiant.earth

    We have language bindings in Shell, Python, Javascript, and more to come! You can view code examples in the area to the right in the respective sections, and you can switch the programming language of the examples with the tabs in the top right.

    We plan to open the documentation to the community for errata, issue tracking, and documentation maintenance.

    Authentication

    The Radiant Earth Foundatiom Data API uses API keys to allow access to the API. You can request a new Data API key using this form.

    The Data API expects for the API key to be included in all API requests to the server in a header that looks like the following:

    apikey={your_api_key}

    Crop Suitability

    Get Crop Suitability By Latitude / Longitude

    
    
    
    
    curl --request POST \
       --url https://api.radiant.earth/crop-suitability/v1.0/crops?apikey={your_api_key} \
       --header "content-type: application/json" \
       --data '{
        "type":"Point",
        "coordinates":[[{latitude}, {longitude}]]
      }'
    

    The above command returns JSON structured like this:

    {
        "Crop": "Generic",
        "Latitude": {latitude},
        "Longitude": {longitude},
        "Suitability": {Suitability Value}
    }
    
    
    

    Make sure to replace your_api_key with your API key, and latitude and longitude with numeric values for your point of interest.

    Radiant Earth Foundation provides pixel accurate crop suitability information. Crop suitability insight is critical ingredient to successful precision agriculture and developing national and regional decision support systems for fodd security. Using various modeling techniques, the API provides a normalized suitability index between 0 (unsuitable) and 1 (suitable).

    Version 1.0 of this index provides suitability for a generic crop (meaning considering average parameters for growth of a crop) using soil properties including: pH index, Cation Exchange Capacity, Soil Organic Carbon Content, and Volumetric Percentage of Coarse Fragments (>2 mm). Currently, data is available all across the African continent, and will be expanded to global land areas in near future. Spatial resolution of the data is ~ 250m (0.0020833330000009018 deg)

    Request should include a GeoJSON data with type, and coordinates. Version 1.0 support type:Point, and provides the suitability at the closest point to the coordinates in the request. Response includes the coordinates of the point that the suitability is retrieved from.

    Get Suitability By Latitude / Longitude

    You can retrieve the suitability using /crops method and posting the latitude and longitude of your point of interest:

    Weather

    The Radiant Earth Foundation API allows you to look up the weather anywhere on the globe, returning (where available):

    For more information, visit the Dark Sky documentation

    Get Weather By Latitude / Longitude

    
    
    
    
    curl -X GET https://api.radiant.earth/weather/37.8267,-122.4233?apikey={your_api_key} \
      -H "Content-Type: application/json"
    
    
    

    Make sure to replace your_api_key with your API key.

    Weather API Call Types

    We provide two types of API requests from Dark Sky to retrieve the weather anywhere in the world:

    Weather Conditions

    The Dark Sky API offers a full collection of meteorological conditions in 39 different languages, including:

    Both forecast and time machine requests return the same weather conditions, in the same convenient JSON format. You can parse the response directly, or use one several community-contributed libraries to interact with our API in the programming language of your choice.

    Terms and Attribution

    Please visit Dark Sky for terms and conditions.

    Air Quality

    
    
    
    
    curl -X GET https://api.radiant.earth/air-quality/api_endpoint_here?apikey={your_api_key} \
      -H "Content-Type: application/json"
    
    
    

    Make sure to replace your_api_key with your API key.

    Air Quality data is available through the Radiant Earth Foundation API using Open AQ. Open AQ aggregates global air quality data from various official sources. Available data includes levels of:

    The data is available filtered by:

    Please see the Open AQ Documentation for details.

    Terms of use and attribution are available in the Open AQ FAQs.

    Populations

    
    
    
    
    curl -X GET https://api.radiant.earth/population/api_endpoint_here?apikey={your_api_key} \ 
      -H "Content-Type: application/json"
    
    
    

    Make sure to replace your_api_key with your API key.

    Global population data is made available through the Radiant Earth Foundation API from the World Population Project by World Data Lab, aggregated from UN demographic data. Using this API, you can access:

    To learn more, see the Population.io documentation.

    Satellites

    
    
    
    
    # Retrieve a satellite by name. Note this search is similar to SQL statement
    # 'LIKE %name_of_satellite%' where all entries containing the 
    # name_of_satellite are returned.
    
    curl -X GET https://api.radiant.earth/satellites/v1.0/name/landsat?apikey={your_api_key} \ 
      -H "Content-Type: application/json"
    

    Because there are two active Landsat satellites in orbing, the above command returns JSON structured like this:

    [
        {
            "apogee_km": "703",
            "class_of_orbit": "LEO",
            "comments": "Remote sensing; polar orbit.",
            "contractor": "Lockheed Martin Missiles & Space",
            "cospar_number": "1999-020A",
            "country_of_contractor": "USA",
            "country_of_operator_or_owner": "USA",
            "country_or_org_of_un_registry": "USA",
            "created_at": "2018-09-21T12:25:59.929517+00:00",
            "date_of_launch": "4/15/1999",
            "detailed_purpose": "Earth Science",
            "dry_mass_kg": "2,200",
            "eccentricity": "7.070000000000001e-05",
            "expected_lifetime_yrs": "15.0",
            "id": 1804,
            "inclination_degrees": "98.2",
            "launch_mass_kg": "2,744",
            "launch_site": "Vandenberg AFB",
            "launch_vehicle": "Delta 2",
            "longitude_of_geo_degrees": "0.0",
            "modified_at": "2018-09-21T12:25:59.929526+00:00",
            "names": [
                {
                    "createdAt": "2018-09-21T12:26:00.384801+00:00",
                    "id": 3665,
                    "modifiedAt": "2018-09-21T12:26:00.384810+00:00",
                    "name": "Landsat 7",
                    "officialName": true,
                    "satId": 1804
                }
            ],
            "norad_number": "25682",
            "operator_or_owner": "National Aeronautics and Space Administration (NASA)/US Geological Survey",
            "perigee_km": "702",
            "period_minutes": "98.8",
            "power_watts": "1,500",
            "purpose": "Earth Observation",
            "source_used_for_orbital_data_1": "www.satellitedebris.net 12/12",
            "source_used_for_orbital_data_2": "http://www.ga.gov.au/acres/prod_ser/landdata.htm",
            "source_used_for_orbital_data_3": "http://nssdc.gsfc.nasa.gov/spacewarn/spx546.html",
            "source_used_for_orbital_data_4": "http://www.floridatoday.com/space/explore/stories/1999/041599ai.htm",
            "source_used_for_orbital_data_5": "http://landsat.usgs.gov/about.html",
            "source_used_for_orbital_data_6": "http://www.sciencemaster.com/jump/space/landsat.php",
            "source_used_for_orbital_data_7": "http://perso.wanadoo.fr/eurospace/espdatabase/index.html",
            "type_of_orbit": "Sun-Synchronous",
            "users": "Government"
        },
        {
            "apogee_km": "705",
            "class_of_orbit": "LEO",
            "comments": "Replacement for Landsat 5.",
            "contractor": "Orbital Sciences Corp.",
            "cospar_number": "2013-008A",
            "country_of_contractor": "USA",
            "country_of_operator_or_owner": "USA",
            "country_or_org_of_un_registry": "USA",
            "created_at": "2018-09-21T12:26:00.568241+00:00",
            "date_of_launch": "2/11/2013",
            "detailed_purpose": "Earth Science",
            "dry_mass_kg": "1,512",
            "eccentricity": "0.00035299999999999996",
            "expected_lifetime_yrs": "5.0",
            "id": 1805,
            "inclination_degrees": "98.2",
            "launch_mass_kg": "2,780",
            "launch_site": "Vandenberg AFB",
            "launch_vehicle": "Atlas 5",
            "longitude_of_geo_degrees": "0.0",
            "modified_at": "2018-09-21T12:26:00.568250+00:00",
            "names": [
                {
                    "createdAt": "2018-09-21T12:26:01.024103+00:00",
                    "id": 3666,
                    "modifiedAt": "2018-09-21T12:26:01.024111+00:00",
                    "name": "Landsat 8",
                    "officialName": true,
                    "satId": 1805
                }
            ],
            "norad_number": "39084",
            "operator_or_owner": "National Aeronautics and Space Administration (NASA)/US Geological Survey",
            "perigee_km": "700",
            "period_minutes": "98.8",
            "power_watts": "4,300",
            "purpose": "Earth Observation",
            "source_used_for_orbital_data_1": "SC - ASCR",
            "source_used_for_orbital_data_2": "http://science.nbcnews.com/_news/2013/05/06/18090996-three-months-after-launch-landsat-8-appears-to-be-working-flawlessly?lite",
            "source_used_for_orbital_data_3": "https://directory.eoportal.org/web/eoportal/satellite-missions/l/landsat-8-ldcm",
            "source_used_for_orbital_data_4": "http://space50.kosmo.cz/s40/2013/INDEX1.HTM",
            "source_used_for_orbital_data_5": "",
            "source_used_for_orbital_data_6": "",
            "source_used_for_orbital_data_7": "",
            "type_of_orbit": "Sun-Synchronous",
            "users": "Government"
        }
    ]
    
    # Users can also search for satellites according to a specific criteria by using
    # the 'search' endpoint. This filter-like functionality enables requests to 
    # be filtered by column, for example return all satellites where
    # country_of_operator_or_owner == "Spain". 
    
    # *Note, due to inconsistent conventions in the source UCS data, all ingested
    # fields are stored as strings. Thus, at this time it is not possible, via
    # the API, to use numerical boolean statements to filter results. 
    
    curl -X GET https://api.radiant.earth/satellites/v1.0/search?country_of_operator_or_owner=India&class_of_orbit=GEO&purpose=Earth Observation&apikey={your_api_key} \
      -H "Content-Type: application/json"
    
    # Alternatively, the /satellites endpoint will accept POST requests with the
    # all arguments stored in the payload.
    
    
    

    Make sure to replace your_api_key with your API key.

    The latest publically-available listing on opertional satellites in earth's orbit is made available through the Radiant Earth Foundation API from the Union of Concerned Scientists. The database is composed of 26 types of data for each satellite, including technical information about each satellite (mass, power, launch date, expected lifetime) and its orbit (apogee, perigee, inclination, and period), as well as information on what the satellite is used for, and who owns, operates, and built the satellite.

    The Satellites API can help answer questions such as:

    To learn more, see the UCS Satellite Database User's Manual or Common Misconceptions about the UCS Satellite Database.

    Errors

    The Data API uses the following error codes. The error codes and their definitions may change from time to time and could impact the overall functioning of your code. Please contact the API administrator should you experience errors unexpectedly.

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The resource requested is not authorized.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access a resource with an invalid method.
    406 Not Acceptable -- You requested a format that isn't JSON.
    410 Gone -- The resource requested has been removed from our API.
    429 Too Many Requests -- Too many API requests within your allowed limits! Slow down!
    500 Internal Server Error -- Houston, we had a problem. Try again later.
    503 Service Unavailable -- Yikes, look out for the fail whale! We're temporarily offline for maintenance. Please try again later.