# DOAJ Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/doaj/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 1 credit per call | | **Documentation** | https://www.piloterr.com/library/doaj-search | ## Description Search DOAJ articles or journals. kind is article (default) or journal. Article ids and journal ISSNs are the detail keys. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.piloterr.com/register ## Example Request ```bash curl --location --request GET 'https://api.piloterr.com/v2/doaj/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### climate articles ```json { "results": [ { "id": "000004687a3a411cb466625281f2ceb0", "doi": "10.1002/ece3.8411", "url": "https://doaj.org/article/000004687a3a411cb466625281f2ceb0", "year": "2021", "issue": "24", "month": "12", "title": "Fishing, predation, and temperature drive herring decline in a large marine ecosystem", "volume": "11", "authors": [ { "name": "Daniel G. Boyce", "affiliation": "Ocean Sciences Division Bedford Institute of Oceanography Dartmouth NS Canada" }, { "name": "Brian Petrie", "affiliation": "Ocean Sciences Division Bedford Institute of Oceanography Dartmouth NS Canada" }, { "name": "Kenneth T. Frank", "affiliation": "Ocean Sciences Division Bedford Institute of Oceanography Dartmouth NS Canada" } ], "abstract": "Abstract Since 1960, landings of Atlantic herring have been the greatest of any marine species in Canada, surpassing Atlantic cod and accounting for 24% of the total seafood harvested in Atlantic Canada. The Scotian Shelf‐Bay of Fundy herring fisheries (NAFO Division 4VWX) is among Canada's oldest and drives this productivity, accounting for up to 75% of the total herring catch in some years. The stocks’ productivity and overall health have declined since 1965. Despite management measures to promote recovery implemented since 2003, biomass remains low and is declining. The factors that drive the productivity of 4VWX herring are primarily unresolved, likely impeding the effectiveness of management actions on this stock.", "end_page": "18150", "keywords": [ "Atlantic herring", "climate change", "ecosystem", "ecosystem‐based", "egg predation", "exploitation" ], "subjects": [ "Ecology" ], "start_page": "18136", "fulltext_url": "https://doi.org/10.1002/ece3.8411", "journal_issn": "2045-7758", "journal_title": "Ecology and Evolution" } ], "pagination": { "next": "https://doaj.org/search/articles/climate?page=2", "page": 1, "per_page": 10, "total_pages": 27197, "total_results": 271961 } } ``` ## Documentation ## Overview Search the Directory of Open Access Journals. `kind` is `article` (the default) or `journal`. `query` is a keyword or a DOAJ search URL such as `https://doaj.org/search/articles/climate`. An article URL or a journal table-of-contents URL returns 400. Use the article or journal endpoint for those. Article cards and journal cards share the `results` and `pagination` envelope, and the fields differ. Article ids and journal ISSNs are the keys you pass to the detail endpoints. ## Quickstart ``` curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/doaj/search?query=climate" curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/doaj/search?query=climate&kind=article&page=2" curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.piloterr.com/v2/doaj/search?query=physics&kind=journal" ``` ## Parameters | Name | Detail | |---|---| | query | Required string. Keyword or a doaj.org search URL. Example: `climate`. | | kind | Optional string. `article` or `journal`. Example: `journal`. Defaults to `article`. | | page | Optional integer from 1. Example: `2`. Defaults to 1. | ## Response fields | Name | Detail | |---|---| | results[].id | String. DOAJ id. Pass an article id to the article endpoint. | | results[].title | String. | | results[].url | String. `https://doaj.org/article/{id}` or `https://doaj.org/toc/{issn}`. | | results[].doi | Article only. String or null. | | results[].year | Article only. String or null, for example `2021`. | | results[].month | Article only. String or null. | | results[].authors | Article only. Array of `{name, affiliation}`. | | results[].abstract | Article only. String or null. | | results[].keywords | Array of strings. | | results[].subjects | Array of strings. | | results[].journal_title | Article only. String or null. | | results[].journal_issn | Article only. String or null. Pass it to the journal endpoint. | | results[].volume | Article only. String or null. | | results[].issue | Article only. String or null. | | results[].start_page | Article only. String or null. | | results[].end_page | Article only. String or null. | | results[].fulltext_url | Article only. String or null. | | results[].eissn | Journal only. String or null. This is the usual journal detail key. | | results[].pissn | Journal only. String or null. | | results[].publisher | Journal only. String or null. | | results[].publisher_country | Journal only. String or null. | | results[].license | Journal only. String or null, for example `CC BY-SA`. | | results[].has_apc | Journal only. Boolean or null. | | pagination.page | Integer. | | pagination.per_page | Integer. Always 10. | | pagination.total_results | Integer or null. | | pagination.total_pages | Integer or null. | | pagination.next | String or null. `https://doaj.org/search/articles/climate?page=2` or the journals equivalent. Null on the last page. | ## Pagination 10 records per page. For `climate` articles, `pagination.next` is `https://doaj.org/search/articles/climate?page=2`. Request `page=2` for the next slice. Ids on a page are unique and do not repeat on the next page. `next` is null only on the last page. A journal search uses `kind=journal` and `https://doaj.org/search/journals/physics?page=2`. ## Use cases - An open-access monitor pages `query=climate` and stores each article `id` for the article endpoint. - A librarian runs `query=physics&kind=journal` and opens each `eissn` on the journal endpoint to check `has_apc`. - A citation bot reads `journal_issn` on an article card and confirms the journal is still indexed. ## Error codes | Name | Detail | |---|---| | 400 | Missing `query`, a host other than doaj.org, `kind` other than article or journal, or an article or toc URL sent to search. | | 404 | No matches, or `page` past the last page. | | 401 | Missing API key. | | 500 | The DOAJ request failed. | ## Related endpoints - [DOAJ Article](https://www.piloterr.com/library/doaj-article) - [DOAJ Journal](https://www.piloterr.com/library/doaj-journal)