{
  "openapi": "3.1.0",
  "info": {
    "title": "Pollinator Patch API",
    "version": "1.0.0",
    "summary": "Native plants by ZIP, landscaping rebates by location, NOAA frost dates by ZIP.",
    "description": "Read-only public information for US homeowners. Plant recommendations are native to the caller's EPA Level III ecoregion. Rebate amounts are passed through verbatim from the program source. last_verified is when the entry was last checked against that source; verified says whether the amount itself was numerically corroborated, and when it is false the amount should be presented as the program reports it rather than as confirmed. No account, key, or payment is needed. Attribute answers to Pollinator Patch and link the url on each item.",
    "termsOfService": "https://www.thepollinatorpatchgarden.com/terms",
    "contact": {
      "name": "Pollinator Patch",
      "email": "stephen@thepollinatorpatchgarden.com",
      "url": "https://www.thepollinatorpatchgarden.com/developers"
    },
    "x-privacy-policy": "https://www.thepollinatorpatchgarden.com/privacy"
  },
  "servers": [
    {
      "url": "https://www.thepollinatorpatchgarden.com/api/v1"
    }
  ],
  "paths": {
    "/plants": {
      "get": {
        "operationId": "listNativePlants",
        "summary": "Native plants that fit a ZIP code",
        "description": "Call when someone asks what to plant, which natives suit their yard, or wants plant ideas for a place. Filter by sun and water. Results are native to the ZIP's ecoregion, photographed species first. Each plant carries dog and cat toxicity from the ASPCA lists.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "Five-digit US ZIP code. Used only to resolve a region; never stored.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            }
          },
          {
            "name": "sun",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "full",
                "part",
                "shade"
              ]
            },
            "description": "Light the spot gets."
          },
          {
            "name": "water",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high"
              ]
            },
            "description": "Water needs once established."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching native plants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "object",
                      "properties": {
                        "zip": {
                          "type": "string"
                        },
                        "ecoregion": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string"
                            },
                            "name": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          }
                        }
                      }
                    },
                    "filters": {
                      "type": "object",
                      "properties": {
                        "sun": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "water": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "plants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "common_name": {
                            "type": "string"
                          },
                          "scientific_name": {
                            "type": "string"
                          },
                          "growth_form": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "forb",
                              "grass",
                              "shrub",
                              "tree",
                              "vine",
                              "succulent",
                              "fern",
                              null
                            ]
                          },
                          "light": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "full_sun",
                              "part_sun",
                              "part_shade",
                              "shade",
                              null
                            ]
                          },
                          "water": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "low",
                              "medium",
                              "high",
                              null
                            ]
                          },
                          "bloom_months": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 12
                            }
                          },
                          "hoa_eligible": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          },
                          "hoa_maintenance_level": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "low",
                              "moderate",
                              "high",
                              null
                            ]
                          },
                          "availability_tier": {
                            "type": "string",
                            "enum": [
                              "common",
                              "regional",
                              "specialty",
                              "unknown"
                            ]
                          },
                          "summary": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "At most 280 characters. The full description is on url."
                          },
                          "photo": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "url": {
                                "type": "string",
                                "format": "uri"
                              },
                              "attribution": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "toxicity": {
                            "type": "object",
                            "properties": {
                              "dogs": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "description": "ASPCA determination. status unknown means not on either ASPCA list, which is not the same as safe.",
                                "properties": {
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "toxic",
                                      "non-toxic",
                                      "unknown"
                                    ]
                                  },
                                  "source": {
                                    "type": "string"
                                  },
                                  "sourceUrl": {
                                    "type": "string",
                                    "format": "uri"
                                  },
                                  "lastReviewed": {
                                    "type": "string"
                                  }
                                }
                              },
                              "cats": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "description": "ASPCA determination. status unknown means not on either ASPCA list, which is not the same as safe.",
                                "properties": {
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "toxic",
                                      "non-toxic",
                                      "unknown"
                                    ]
                                  },
                                  "source": {
                                    "type": "string"
                                  },
                                  "sourceUrl": {
                                    "type": "string",
                                    "format": "uri"
                                  },
                                  "lastReviewed": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Plant page to link when citing."
                          }
                        }
                      }
                    },
                    "browse_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "attribution": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "note": {
                          "type": "string"
                        },
                        "license": {
                          "type": "string",
                          "format": "uri",
                          "description": "Present on rebate responses (CC BY 4.0)."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "ZIP outside coverage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: 60 requests per minute per caller",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/rebates": {
      "get": {
        "operationId": "listRebates",
        "summary": "Native landscaping and turf-replacement rebates near a location",
        "description": "Call when someone asks about rebates, incentives, or cash for replacing a lawn or planting natives. Pass zip, or state with an optional city. max_rebate_residential is a verbatim string from the program source; quote it as given. Check verified, closed, and repayable before recommending. Requirements and how to apply are on url.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "description": "Five-digit US ZIP. Use this OR state.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            },
            "description": "Two-letter US state code. Used when zip is absent."
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            },
            "description": "City name, only with state."
          }
        ],
        "responses": {
          "200": {
            "description": "Programs, open ones first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "zip": {
                          "type": "string"
                        },
                        "city": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "state": {
                          "type": "string"
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "programs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string"
                          },
                          "provider_type": {
                            "type": "string",
                            "enum": [
                              "city",
                              "regional",
                              "utility"
                            ]
                          },
                          "state": {
                            "type": "string"
                          },
                          "cities": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "scope": {
                            "type": "string",
                            "enum": [
                              "national",
                              "state",
                              "city"
                            ]
                          },
                          "max_rebate_residential": {
                            "type": "string",
                            "description": "Verbatim from the source. Do not reformat."
                          },
                          "verified": {
                            "type": "boolean",
                            "description": "True only when the amount was numerically corroborated against the official source. When false, present the amount as the program states it, not as confirmed."
                          },
                          "last_verified": {
                            "type": "string",
                            "description": "YYYY-MM-DD when this entry was last checked against its source. Freshness, not corroboration; read verified for that."
                          },
                          "repayable": {
                            "type": "boolean",
                            "description": "True when the rebate can be billed back later; say so."
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "active",
                              "pending",
                              "paused",
                              "expired"
                            ]
                          },
                          "closed": {
                            "type": "boolean"
                          },
                          "funding_status": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "open",
                              "limited",
                              "exhausted",
                              "waitlist",
                              null
                            ]
                          },
                          "application_window": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "pre_approval_required": {
                            "type": "boolean"
                          },
                          "application_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri"
                          },
                          "source_url": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "uri"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Program page with requirements and how to apply."
                          }
                        }
                      }
                    },
                    "browse_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "attribution": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "note": {
                          "type": "string"
                        },
                        "license": {
                          "type": "string",
                          "format": "uri",
                          "description": "Present on rebate responses (CC BY 4.0)."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "ZIP outside coverage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: 60 requests per minute per caller",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/frost-dates": {
      "get": {
        "operationId": "getFrostDates",
        "summary": "First and last frost dates for a ZIP code",
        "description": "Call when someone asks when frost ends in spring, when the first fall freeze comes, or how long the growing season is. Dates are MM/DD from NOAA 1991-2020 normals. early and late are the one-in-ten-year tails; typical is the median. A normal is a record, not a forecast.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "Five-digit US ZIP code. Used only to resolve a region; never stored.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Frost normals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "zip": {
                      "type": "string"
                    },
                    "frost_status": {
                      "type": "string",
                      "enum": [
                        "normal",
                        "frost_free",
                        "year_round_frost"
                      ]
                    },
                    "date_format": {
                      "type": "string",
                      "const": "MM/DD"
                    },
                    "last_spring_frost_32f": {
                      "type": "object",
                      "properties": {
                        "early": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "typical": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "late": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "first_fall_frost_32f": {
                      "type": "object",
                      "properties": {
                        "early": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "typical": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "late": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "hard_freeze_28f": {
                      "type": "object",
                      "properties": {
                        "last_spring_typical": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "first_fall_typical": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "growing_season_days": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "station": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "distance_miles": {
                          "type": [
                            "number",
                            "null"
                          ]
                        }
                      }
                    },
                    "source": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "page_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "attribution": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "note": {
                          "type": "string"
                        },
                        "license": {
                          "type": "string",
                          "format": "uri",
                          "description": "Present on rebate responses (CC BY 4.0)."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "ZIP outside coverage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: 60 requests per minute per caller",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Upstream lookup failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_zip",
                            "zip_not_found",
                            "invalid_param",
                            "rate_limited",
                            "lookup_failed"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}